Explicit Sending and Receiving of Messages

sending messages p4_send p4_sendr p4_sendx p4_sendrx p4_sendb p4_sendbr p4_sendbx p4_sendbrx
\begin{example} p4_send(type,to,msg,len) p4_sendr(type,to,msg,len) p4_sendx(type... ...,to,msg,len,datatype) \par int type, to, len, datatype; char *msg; \end{example}

Each of these procedures sends a message. The type argument is an integer value chosen by the user to represent a message type. The to argument is an integer value that specifies the p4-id of the process that should receive the message. The len argument contains the length of the message to be passed. Note that some of the procedures have a ``b'' in their name, e.g. p4_sendb. These procedures assume that the msg is in a buffer that the user obtained earlier via a p4_msg_alloc; otherwise, the buffer is assumed to be in the user's local space, and may cause the message to be copied internally. The procedures with an ``r'' in the name do not return until an acknowledgement is received from the to process (the ``r'' stands for rendezvous). Those procedures with an ``x'' in the name take an extra argument (datatype) that specifies the type of data in the message; these procedures will use that information to call XDR for data conversion if the message is being passed to a machine of a different architecture, i.e. where the internal representation may be different.

p4_messages_available
\begin{example} BOOL p4_messages_available(req_type,req_from) int *req_type,*req_from; \end{example}
returns a BOOL value indicating whether the process has any messages available or not. The parameters req_type and req_from are both pointers to integers; they are used as both input and arguments. On input, req_type has a value that indicates the type of message that the user wishes to check for availability (-1 indicates any type). The variable req_from is used similarly to indicate who a message is desired from.

receiving messages p4_recv
\begin{example} int p4_recv(req_type,req_from,msg,len_rcvd) int *req_type,*req_from,*len_rcvd; char **msg; \end{example}
takes four arguments. The msg argument is a pointer to a pointer to a char. If this value is NULL, then p4 will allocate the buffer for the message according to its length. That is, one need not know ahead of time the length of a message being received. If this value is not NULL, then it points to a p4 message buffer that the user has obtained via p4_msg_alloc. The len_rcvd argument is a pointer to an integer that is assigned the length of the received message. Req_type and req_from are both pointers to integers; they are used as both input and arguments. On input, req_type has a value that indicates the type of message that the user wishes to receive (-1 indicates any type). It will block until a message of that type is available. Req_from is used similarly to indicate who a message is desired from. One important note about this procedure is that it obtains the area in which to place a message, and the user must explicitly free that area when finished with it (see p4_msg_free). There is an option available with p4_recv in which the user can provide his own buffer rather than having p4 allocate it. To do this, the user points msg to a buffer that he must obtain via a call to p4_msg_alloc (see below). Then he assigns len_rcvd a value which is the length of that buffer. In this case, len_rcvd is both an input and output variable. In addition, no p4_msg_free need be performed if the same buffer is going to be re-used multiple times.

allocating buffers p4_msg_alloc
\begin{example} char *p4_msg_alloc(len) int len; \end{example}
obtains a pointer to a buffer area that can be used to receive a message. This procedure should be used for this task because a message has hidden information which the user is unaware of and therefore should not use malloc to obatin the area.

deallocating buffers p4_msg_free
\begin{example} VOID p4_msg_free(m) char *m; \end{example}
frees the message pointed to by m. This procedure should be used for this task because a message has hidden information which the user is unaware of and therefore cannot be freed by the user.

Global Operations, ,Explicit Sending and Receiving of Messages,Functions for Message Passing